package br.unicamp.mc715.transport;

import java.io.Serializable;

import br.unicamp.mc715.common.MC715IOException;
import br.unicamp.mc715.common.MC715SerializationException;

/**
 * This interface represents a generic multicast transport. It allows to send
 * and receive multicast and unicast messages. Unicast addressing is done using
 * the transport id object returned by <code>getId()</code>. <p>
 *
 */
public interface Transport {

    /**
     * Returns the unique id of this transport. This id can be used for
     * unicast addressing. <p>
     * 
     * @return the unique id of this transport.
     */
    TransportId getId();
    
    /**
     * Receives a message from this transport. This method behaves exactly
     * like <code>receiveMessage(int)</code> but blocks until a message is
     * available. <p>
     * 
     * @return the received message.
     * @throws MC715IOException if an I/O error occurs.
     * @throws MC715SerializationException if a serialization error occurs.
     * @see Transport#receiveMessage(int)
     */
    Message receiveMessage()
        throws MC715IOException, MC715SerializationException;
    
    /**
     * Receives a message from this transport. This method blocks until
     * a message is available or a specified number or milliseconds passes.
     * The received message can either be a multicast or unicast one. Unicast
     * messages have as receiver this transport id, multicast messages have
     * <code>null</code> as receiver. <p>
     * 
     * @param timeout the time in milliseconds to wait for a message, 0 to
     *                wait forever.
     * @return the received message.
     * @throws MC715IOException if an I/O error occurs.
     * @throws MC715SerializationException if a serialization error occurs.
     */
    Message receiveMessage(int timeout)
        throws MC715IOException, MC715SerializationException;
    
    /**
     * Sends a multicast message. All connected transports, including this
     * one, will receive this message. Message delivery is best effort only,
     * there is no guarantee the message will reach the intended
     * destinations. <p>
     * 
     * @param message the message to be sent.
     * @throws MC715IOException if an I/O error occurs.
     * @throws MC715SerializationException if a serialization error occurs.
     */
    void sendMessage(Serializable message)
        throws MC715IOException, MC715SerializationException;
    
    /**
     * Sends a unicast message to a transport identified by a transport id.
     * Message delivery is best effort only, there is no guarantee the
     * message will reach the intended destination. <p>
     * 
     * @param message the message to be sent.
     * @param destination the destination.
     * @throws MC715IOException if an I/O error occurs.
     * @throws MC715SerializationException if a serialization error occurs.
     */
    void sendMessage(Serializable message, TransportId destination)
        throws MC715IOException, MC715SerializationException;
    
    /**
     * Clears the buffer for messages received.
     */
    void clearBuffer();

}
